home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Gold Collection / Software Vault - The Gold Collection (American Databankers) (1993).ISO / cdr49 / 123_01.zip / PP.DOC < prev    next >
Text File  |  1993-06-07  |  7KB  |  278 lines
  1. .bp 1
  2. .in 0
  3. .he 'PP (1)'10/1/79'PP (1)'
  4. .fo ''-#-''
  5. .in 7
  6. .ti -7
  7. NAME
  8. .br
  9. pp - pre-processor for the C programming language
  10.  
  11. .ti -7
  12. SYNOPSIS
  13. .br
  14. pp <infile> [<outfile>] [-d]\n");
  15.  
  16. .ti -7
  17. DESCRIPTION
  18. .br
  19. PP is a pre-processor for use with the C programming language.
  20. PP is not simply a transliteration of the RATFOR tool called MACRO;
  21. it conforms to the "official" format of the C preprocessor as defined
  22. in the K&R C Programming Language book.
  23. The output file can be fed into the BDS C compiler;
  24. or any other compiler (and other languages?) for
  25. which the input was intended.
  26.  
  27. PP reads its input file and writes to its output file.
  28. if <outfile> is not given, output will be placed in
  29. <infile>.PP.
  30. The optional -d turns on the debug mode which is only
  31. useful if you want to watch what goes on inside the
  32. program as it crunches files.
  33.  
  34. PP has #include file capability and
  35. symbolic parameter substitution (macros).
  36.  
  37. Macros permit the definition of
  38. symbolic constants so that subsequent
  39. occurrences of the constant are replaced by the defining
  40. string of characters.
  41. The general form of a macro definition is
  42.  
  43.     #define name replacement-text
  44.  
  45. All subsequent occurrences of "name" in the file will be replaced
  46. by "replacement-text".
  47. The placement of blanks in definitions is significant;
  48. they should only appear in the replacement
  49. text where desired.
  50. Upper and lower case letters are also significant.
  51. The replacement text may be more than one
  52. line long.
  53. However, when an entire macro definition is followed immediately by a newline,
  54. the newline is discarded.
  55. This prevents extraneous blank lines from appearing in the output.
  56.  
  57. Nesting of macros is allowed, as is recursion.
  58.  
  59. An elementary example of a macro is:
  60.  
  61.     #define EOF -1
  62.  
  63. Thereafter, all occurrences of "EOF" in the file would be replaced
  64. by "-1".
  65.  
  66. Macros with arguments may also be specified.
  67. That means you can write something like:
  68.  
  69.     #define max(a,b) (a) > (b) ? (a) : (b)
  70.  
  71. which will replace:
  72.  
  73.     max(x+1,y-1)
  74.  
  75. with:
  76.  
  77.     (x+1) > (y-1) ? (x+1) : (y-1)
  78.  
  79. Here "max(a,b)" is a template with two parameters: a and b.
  80. When the preprocessor sees "max(x+1,y-1)"
  81. it replaces the first parameter (a) in the definition
  82. with "x+1" and the second parameter ("b") with "y-1".
  83. Notice that the "(" must follow "max" with no intervening spaces.
  84. That's so the preprocessor can differentiate
  85. between argumented and non-argumented macros, e.g.,
  86. "#define ERROR (-1)".
  87.  
  88. Notice that the a and b in the definition of max are surrounded
  89. by parentheses. This is often a good idea; it avoids
  90. problems that might occur with precedence rules, e.g.:
  91.  
  92.     #define div(a,b) a/b
  93.     ... div(x+2,5)
  94.  
  95. would result in "x+2/5" which is interpreted as x+(2/5)
  96. instead of the intended "(x+2)/5".
  97.  
  98. As another example, 
  99.  
  100. .nf
  101. #define copen(filename,mode,filedes)\n
  102.     filedes = open(filename,mode)\n
  103.     if (filedes == ERROR) {\n
  104.         cant(filename);\n
  105.     }
  106. .br
  107. .fi
  108.  
  109. would define a macro called copen that, when called by
  110.  
  111.     copen(name, READ, fd)
  112.  
  113. would expand into
  114.  
  115. .nf
  116.     fd = open(name,READ)
  117.     if (fd == ERROR) {
  118.         cant(name);
  119.     }
  120. .br
  121. .fi
  122.  
  123. .ti -7
  124. FILES
  125. .br
  126. None
  127.  
  128. .ti -7
  129. SEE ALSO
  130. .br
  131. Kernighan and Plauger's "Software Tools", pages. 251-283
  132. .br
  133.  
  134. .ti -7
  135. DIAGNOSTICS
  136. .br
  137. arith evaluation stack overflow
  138. .in +5
  139. The max level of nested arithmetic expressions has been exceeded.
  140. The size is set by the MAXSTACK definition in the source code.
  141. .sp
  142. .in -5
  143. arg stack overflow
  144. .br
  145. .in +5
  146. The maximum number of total arguments has been exceeded;
  147. the size is set by the ARGSIZE definition in the source code.
  148. .in -5
  149. .sp
  150. call stack overflow
  151. .br
  152. .in +5
  153. The maximum level of nesting of definitions has been exceeded.
  154. The size is set by the CALLSIZE definition in the source code.
  155. .in -5
  156. .sp
  157. EOF in string
  158. .br
  159. .in +5
  160. An end-of-file has been encountered before a bracketed string has
  161. been terminated.
  162. .in -5
  163. .sp
  164. evaluation stack overflow
  165. .br
  166. .in +5
  167. The total number of characters permitted for
  168. name, definition, and arguments
  169. has been exceeded.
  170. Set by the EVALSIZE definition in the source code.
  171. .in -5
  172. .sp
  173. unexpected EOF
  174. .br
  175. .in +5
  176. An end-of-file was reached before the macro definition was terminated.
  177. .in -5
  178. .sp
  179. filename: can't open
  180. .br
  181. .in +5
  182. The indicated file could not be opened.
  183. .in -5
  184. .sp
  185. filename: can't #include
  186. .br
  187. .in +5
  188. The indicated file could not be included via the includ builtin.
  189. .in -5
  190. .sp
  191. #includs nested too deeply
  192. .br
  193. .in +5
  194. #includes were nested deeper than the system would allow.
  195. The number is determined by the MAXOFILES definition in the
  196. general symbols definition file.
  197. .in -5
  198. .sp
  199. expression: invalid infix expression
  200. .br
  201. .in +5
  202. There is a syntax error in the indicated infix expression as
  203. passed to the expr builtin.
  204. .in -5
  205. .sp
  206. too many characters pushed back
  207. .br
  208. .in +5
  209. A macro expansion is too large to be rescanned.
  210. The size is set by the BUFSIZE definition in the source code.
  211. .in -5
  212. .sp
  213. name: too many definitions
  214. .br
  215. .in +5
  216. The table space for macro definitions has been exhausted; this
  217. occurred upon the definition of the indicated macro.
  218. .in -5
  219. .sp
  220. token too long
  221. .br
  222. .in +5
  223. A name or symbol in the input was longer than the token buffer.
  224. Size is determined by the MAXTOK definition in the source code.
  225. .in -5
  226. .sp
  227. .ti -7
  228. AUTHORS
  229. .br
  230. Original by Kernighan and Plauger, with enhancements by
  231. David Hanson and friends (U. of Arizona) and Philip
  232. Scherrer (Stanford U.)
  233.  
  234. Modifications for "C" syntax by:
  235.  
  236.     Robert T. Pasky
  237.     36 Wiswall Rd
  238.     Newton Centre, MA 02159
  239.     (617) 964-3641
  240.  
  241. A stab at documentation made by:
  242.  
  243.     Edward K. Ream
  244.     1850 Summit Ave.
  245.     Madison, WI 53705
  246.     (608) 231 - 2952
  247.  
  248. .fi
  249. .sp
  250. .ti -7
  251. BUGS/DEFICIENCIES
  252. .br
  253. 1.  This macro processor is incompatible with the one included
  254. in the ratfor preprocessor.
  255. I (E. K. Ream) would also be quite surprised (shocked may be more like it)
  256. if it also followed all the subtle nuances of the Unix C preprocessor.
  257.  
  258. 2.  This program has NOT been rigorously tested
  259. and, as provided here, is quite limited in its array
  260. size (it's easy enough to increase the defines for
  261. the array sizes if you have lots of memory).
  262. The proportions allocated among the various arrays
  263. may also need tuning. For example, if you like to use
  264. lots of short define strings you might increase MAXTOK
  265. and MAXDEF. On the other hand, if you have relatively
  266. few defines but they tend to be long-winded, you could
  267. shorten these in favor of increasing MAXTBL (and
  268. possibly DEFSIZ).
  269.  
  270. 3.  This preprocessor does not suppost the #if, #ifdef, #ifndef,
  271. #else, #endif or #line preprocessor directives.
  272.  
  273. 4.  Almost all of this documentation may be in error, since it
  274. was not written by the author of the program.
  275.  directives.
  276.  
  277. 4.  Almost all of this documentation may be in error, since it
  278. was not written by the author of th